[Appendix A] A.3 chat
Author: Craig Hunt
Date: 1999-02-04T01:42:42Z

#

| Appendix A PPP Tools |

## A.3 chat

chat is a general-purpose scripting language that is used to control the modem, dial the remote server, and perform the remote system login. chat is less powerful than dip but is widely used. The "expect/send" structure of a chat script is the fundamental structure used in most scripting languages.

A chat script is composed of expect/send pairs. These pairs consist of the string expected from the remote system, separated by whitespace from the response that is sent to the remote host when the expected string is received. If no string is expected from the remote system, two quotes (`""`) or two apostrophes (`"`) are used to "expect nothing." A simple chat script is:

>     "" \r name> jane word> TOga!toGA

The script expects nothing (`""`) until it sends the remote system a carriage return (`\r`). Then the script expects the remote system to send the string `name>`, which is part of the system's `Username>` prompt. In response to this prompt, the script sends the username `jane`. Finally the script waits for part of the `Password>` prompt and responds with `TOga!toGA`. A script this simple can be defined directly on the chat command line:

>     % chat -v -t30 "" \r name> jane word> TOga!toGA

This command runs chat in verbose mode, sets the length of time the script waits for an expected string to 30 seconds, and then executes the simple login script described above.

The syntax of the chat command is:

  chat [`options`] [`script`]

The chat command options are:

-v

  Runs the chat script in verbose mode. Verbose mode logs informational messages via syslogd.

-V

  Runs the chat script in stderr verbose mode. The stderr verbose mode displays informational messages on the stderr device. See Chapter 6 for an example of this being used with pppd.

-t `timeout`

  Sets the maximum time to wait for an expected string. If the expected string is not received in `timeout` seconds, the reply string is not sent and the script terminates&amp;amp;amp;mdash;unless an alternate send is defined. If defined, the alternate send (more about this later) is sent and the remote system is given one more `timeout` period to respond. If this fails, the script is terminated with a nonzero error code. By default, the timeout period is 45 seconds.

-f `scriptfile`

  Reads the chat script from the `scriptfile` instead of from the command line. Multiple lines of expect/send pairs are permitted in the file.

-r `reportfile`

  Writes the output generated by REPORT strings to the `reportfile`. By default, REPORT strings are written to stderr. The REPORT keyword is covered below.

In order to make the scripts more useful and robust, chat provides special keywords, escape sequences, and alternate send/expect pairs that can be used in the script. First let's look at the five chat keywords.

Two keywords transmit special signals to the remote system. The keyword `EOT` sends the End of Transmission character. On UNIX systems this is usually the End of File character, which is a CTRL-D. The `BREAK` keyword sends a line break to the remote system. The three remaining keywords define processing characteristics for the script itself.

The `TIMEOUT` keyword defines the amount of time to wait for an expected string. Because it is defined inside the script, the timeout value can be changed for each expected string. For example, assume you want to allow the remote server 30 seconds to display the initial `Username>` prompt but only 5 seconds to display `Password>` once the username has been sent. Enter this script command:

>     TIMEOUT 30 name> karen TIMEOUT 5 word> beach%PARTY

The `ABORT` keyword and the `REPORT` keyword are similar. They both define strings that, when received, cause a special action to take place. The `ABORT` keyword defines strings that cause the script to abort if they are received when the system is expecting the string CONNECT from the modem. The `REPORT` keyword defines substrings that determine what messages received on the serial port should be written to stderr or the report file. A sample chat script file illustrates both of these keywords:

>     REPORT CONNECT
>     ABORT BUSY
>     ABORT 'NO CARRIER'
>     ABORT 'RING - NO ANSWER'
>     "" ATDT5551234
>     CONNECT \r
>     name> karen
>     word> beach%PARTY

The first line says that any message received by the script that contains the word CONNECT will be logged. If the -r command-line option was used when chat was started, the message is logged in the file defined by that option. Otherwise the message is displayed on stderr. The point of this command is to display the modem's connect message to the user. For example: the complete message might be CONNECT 28,800 LAPM/V, which tells the user the link speed and the transmission protocol used by the modems. The CONNECT message means success. The next three lines of the script begin with the keyword `ABORT` and define the modem messages that mean failure. If the modem responds with BUSY, NO CARRIER, or RING - NO ANSWER, the script aborts.

The last four lines are the basic expect/send pairs we have seen repeatedly in this section. We expect nothing (`""`) and send the dial command to the modem (`ATDT`). We expect CONNECT from the modem and send a carriage return (`\r`) to the remote server. We expect `Username>` from the remote server and send `karen`. Finally, we expect `Password>` from the server and send `beach%PARTY`.

chat extends the standard expect/send pair with an alternate send and an alternate expect to improve robustness. You may define an alternate send string and an alternate expect value to be used when the script times out waiting for the primary expected value. The alternate send and the alternate expect are indicated in the script by preceding them with dashes. For example:

>     gin:-BREAK-gin: becca

In this sample we wait for the string `gin:` and send the string `becca`. The first string and the last string compose the standard expect/send pair. The alternate send/expect is only used if the timer expires and the expected `gin:` string has not been received. When this occurs, the script sends a line break, restarts the timer, and waits for `gin:` again, because that is what our alternate send/expect pair (`-BREAK-gin:`) tells the script to do. Note that unlike the standard expect/send pair, in the send/expect pair a value is transmitted before a string is expected, i.e., the send comes before the expect. Another example more in keeping with our other script examples is:

>     name>&amp;amp;amp;mdash;name> karen

Here the script expects the `name>` string. If it is not received, the script sends an empty line, which is simply a carriage return, and again waits for the `name>` string. This action is dictated by the alternate send/expect pair, `&amp;amp;amp;mdash;name>`. The pair begins with a dash that signals the start of the send string, but the next character is the second dash that marks the beginning of the alternate expect string. There is no send string. It is this "empty string" that causes the script to send a single return character. This example is more common than the BREAK example shown above, though a little harder to explain.

The carriage return character is not the only special character that can be sent from a chat script. chat provides several escape sequences for sending and receiving special characters. Table 13.2 lists these.

Table A.2: chat Escape Sequences
Escape Sequence | Meaning
--- | ---
\b | The backspace character.
\ | Send without the terminating return character.
\d | Delay sending for one second.
\K | Send a BREAK.
\n | Send a newline character.
\N | Send a null character.
\ | Delay sending 1/10th of a second.
\q | Send the string but don't log it.
\r | The carriage return.
\s | The space character.
\t | The tab character.
\\ | The backslash character.
\ddd | The ASCII character with the octal value ddd.
^C | A control character.

All of the escape sequences start with a backslash (\) except for the sequence used to enter a control character. Control characters are entered as a caret (^) followed by an uppercase letter. For example control X is entered as ^X. The escape sequences that are described in Table 13.2 with the words "send" or "sending" can only be used in a send string; all others can be used in either a send or expect string. Several escape sequences are used in the following example:

>     "" \d\d^G\p^G\p\p^GWake\sUp!\nSleepy\sHead!

Expect nothing (`""`). Wait two seconds (`\d\d`). Send three ASCII BELL characters, which is CTRL-G on the keyboard, at intervals of 1/10 of a second (`^G\p^G\p\p^G`). Send the string `Wake Up!`. Go to a new line (`\n`) and send the string `Sleepy Head!`.

A.2 The PPP Daemon |  | B. A gated Reference